<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Nested transactions</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 12.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_cursor.html" title="Transactional cursors" />
    <link rel="next" href="transapp_admin.html" title="Environment infrastructure" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Nested transactions</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_cursor.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 12.  Berkeley DB Transactional Data Store Applications </th>
          <td width="20%" align="right"> <a accesskey="n" href="transapp_admin.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_nested"></a>Nested transactions</h2>
          </div>
        </div>
      </div>
      <p>
        Berkeley DB provides support for nested transactions. Nested
        transactions allow an application to decompose a large or
        long-running transaction into smaller units that may be
        independently aborted.
    </p>
      <p>
        Normally, when beginning a transaction, the application will
        pass a NULL value for the parent argument to <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a>. If,
        however, the parent argument is a <a href="../api_reference/C/txn.html" class="olink">TXN</a> handle, the newly
        created transaction will be treated as a nested transaction
        within the parent. Transactions may nest arbitrarily deeply.
        For the purposes of this discussion, transactions created with
        a parent identifier will be called <span class="emphasis"><em>child
       transactions</em></span>.
    </p>
      <p>
        Once a transaction becomes a parent, as long as any of its
        child transactions are unresolved (that is, they have neither
        committed nor aborted), the parent may not issue any Berkeley
        DB calls except to begin more child transactions, or to commit
        or abort. For example, it may not issue any access method or
        cursor calls. After all of a parent's children have committed
        or aborted, the parent may again request operations on its own
        behalf.
    </p>
      <p>
        The semantics of nested transactions are as follows. When a
        child transaction is begun, it inherits all the locks of its
        parent. This means that the child will never block waiting on
        a lock held by its parent. Further, locks held by two children
        of the same parent will also conflict. To make this concrete,
        consider the following set of transactions and lock
        acquisitions.
    </p>
      <p>
        Transaction T1 is the parent transaction. It acquires a
        write lock on item A and then begins two child transactions:
        C1 and C2. C1 also wants to acquire a write lock on A; this
        succeeds. If C2 attempts to acquire a write lock on A, it will
        block until C1 releases the lock, at which point it will
        succeed. Now, let's say that C1 acquires a write lock on B. If
        C2 now attempts to obtain a lock on B, it will block. However,
        let's now assume that C1 commits. Its locks are
        anti-inherited, which means they are given to T1, so T1 will
        now hold a lock on B. At this point, C2 would be unblocked and
        would then acquire a lock on B.
    </p>
      <p>
        Child transactions are entirely subservient to their parent
        transaction. They may abort, undoing their operations
        regardless of the eventual fate of the parent. However, even
        if a child transaction commits, if its parent transaction is
        eventually aborted, the child's changes are undone and the
        child's transaction is effectively aborted. Any child
        transactions that are not yet resolved when the parent commits
        or aborts are resolved based on the parent's resolution --
        committing if the parent commits and aborting if the parent
        aborts. Any child transactions that are not yet resolved when
        the parent prepares are also prepared.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_cursor.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="transapp_admin.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Transactional cursors </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Environment
        infrastructure</td>
        </tr>
      </table>
    </div>
  </body>
</html>
